Machine Groups

Machine groups are used to organize and track the machines that are included in a scan. You can manage machine groups and the contents of each machine group. All machine types are supported by the REST API except for offline workstation virtual machines.

Base URL

        https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups

Supported Requests

Method	URL	Input	Return
DELETE	https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/{group Id}		None
	https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/{group Id}/discoveryFilters	Delete filters	Success code
	https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/{group Id}/discoveryFilters/{filter Id}		Success code
	https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/{group Id}/virtualMachineDiscoveryFilters	Delete filters	Success code
	https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/{group Id}/virtualMachineDiscoveryFilters/{filter Id}		Success code
GET	https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups	URL Parameters	MachineGroup[]
	https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/{group Id}		MachineGroup
	https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/{group Id}/UsedBy		UsedBy
	https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/{group Id}/discoveryFilters	URL Parameters	Discovery Filters
	https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/{group Id}/discoveryFilters/{filterId}		Discovery Filters
	https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/{group Id}/virtualMachineDiscoveryFilters	URL Parameters	VirtualMachineDiscoveryFilter
	https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/{group Id}/virtualMachineDiscoveryFilters/{filterId}		VirtualMachineDiscoveryFilter
POST	https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups	Request Body	MachineGroup
	https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/{group Id}/discoveryFilters	DiscoveryFilters Request Body	MachineGroup
	https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/{group Id}/virtualMachineDiscoveryFilters	VMDiscoveryFilters Request Body	MachineGroup
PUT	https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/{group Id}	Request Body	Success code
	https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/{Id}/credentials	Credential URL Parameters	Success code
	https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/{group Id}/discoveryFilters/{filter Id}	DiscoveryFilter Request Body	Success code
	https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/{group Id}/discoveryFilters/{filter Id}/credentials	DiscoveryFilter Credential URL Parameters	Success code
	https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/{group Id}/virtualMachineDiscoveryFilters/{filter Id}	VMDiscoveryFilter Request Body	Success code
	https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/{group Id}/virtualMachineDiscoveryFilters/{filter Id}/credentials	DiscoveryFilter Credential URL Parameters	Success code

Input Models

Delete Filters

Name	Required?	Type	Default Value	Description
Ids	Yes	Int32[]	None	The Machine IDs. The values must be specified within an array.
errorPolicy	No		Throw	errorPolicy=Throw means the entire request will be rejected errorPolicy=Omit means the problem area will be omitted but the rest of the request will be completed.

URL Parameters

Name	Type	Description
count	Integer	Provide the count of items to return. The default is 10 and the maximum value is 1000.
The following do not apply to discoveryFilters or virtualMachineDiscoveryFilters GET requests.
createdByMe	Boolean	Returns only those items created by the user. This parameter will be removed in a future release and should only be used in legacy requests.
name	String	Returns the items whose name matches the specified name.
start	Integer	Sets the starting point. The items are sorted by their unique identifier and the starting point is the index into that sorted list.
path	String	Returns the items containing the path.

Credential URL Parameters

Name	Required?	Type	Default Value	Description
adminCredential	No	Guid	None	The unique identifier of the associated admin credential.

DiscoveryFilter Credential URL Parameters

Name	Required?	Type	Default Value	Description
adminCredentialId	No	Guid	None	The unique identifier of the associated admin credential.
containerCredentialId	No	Guid	None	The unique identifier of the associated browse or container credential.

Request Body

Name	Required?	Type	Default Value	Description
connectionMethod	No	Enum	None	Specifies the method used to connect to the machines within the machine group. Valid values are: Inherit: Use the global setting specified on the Scan Options dialog available from Tools > Options > Scan. For more information, see Ivanti Security Controls help (opens in a new window).This is the default. IPAddress: A connection is made by IP address after name/machine resolution is performed. Fqdn: A connection is made using the Fully Qualified Domain Name (FQDN). This supports SPN name validation, which may be required in networks using Kerberos authentication.
credentialId	No	Guid	None	The unique identifier of the credential associated with the machine group.
description	No	String	None	Provides a description of the machine group.
discoveryFilters	No	DiscoveryFilter Request Body	None	Specifies the machines and containers in the machine group.
errorPolicy	No	String	Omit	Determines if the call will throw an error when encountering an invalid ID. Throw: The entire request will be rejected. Omit: The problem area will be omitted but the rest of the request will be completed.
name	Yes	String	None	The unique, user-defined name of the machine group.
path	No	String	None	The path that describes the location of the machine group within the My Machine Groups list in the navigation pane. Example: Lab\Servers
serverFilterTypes	No	ServerFilterTypes[]	All	The server filter types that will be included when scanning a machine group.
virtualMachineDiscoveryFilters	No	VMDiscoveryFilter Request Body	None	Specifies the hosted virtual machines in the machine group.

DiscoveryFilters Request Body

Name	Required?	Type	Default Value	Description
discoveryFilters[]	No	DiscoveryFilter Request Body	None	Specifies the discovery filter items in the machine group.
errorPolicy	No	String	Omit	Determines if the call will throw an error when encountering an invalid ID. Throw: The entire request will be rejected. Omit: The problem area will be omitted but the rest of the request will be completed.

Name

Required?

Type

Default Value

Description

discoveryFilters[]

DiscoveryFilter Request Body

None

Specifies the discovery filter items in the machine group.

errorPolicy

String

Omit

Determines if the call will throw an error when encountering an invalid ID.

Throw: The entire request will be rejected.
Omit: The problem area will be omitted but the rest of the request will be completed.

DiscoveryFilter Request Body

Name	Required?	Type	Default Value	Description
adminCredentialId	No	Guid	None	The unique identifier of the credential associated with the admin credential.
category	No	DiscoveryFilterType	None	The type of filter or machine group item.
containerCredentialId	No	Guid	None	The unique identifier of the associated browse or container credential.
includeChildOU	No	Boolean	None	The child OUs.
isExcluded	No	Boolean	None	Is the item included or excluded during the operation.
name	Yes	String	None	The filter or endpoint name.
note	No	String	None	A user-specified note or description.
sshServerValidationMode	No	String	Blocked	Specifies if an SSH connection can be used when the console communicates with endpoints that support SSH and for which SMB fails. There are potential security risks when using an SSH connection, so be sure to review the SSH Authentication topic before making a decision. Blocked: The console will not be able to make an SSH connection with the endpoints. SkipServerAuthentication: An SSH connection is allowed between the console and the endpoints without the use of SSH server authentication. This should only be used if you are certain that the endpoints are trusted and safe Linux machines.

VMDiscoveryFilters Request Body

Name	Required?	Type	Default Value	Description
virtualMachineDiscoveryFilters[]	No	VMDiscoveryFilter Request Body	None	Specifies the hosted virtual machine discovery filter items in the machine group.
errorPolicy	No	String	Omit	Determines if the call will throw an error when encountering an invalid ID. Throw: The entire request will be rejected. Omit: The problem area will be omitted but the rest of the request will be completed.

Name

Required?

Type

Default Value

Description

virtualMachineDiscoveryFilters[]

VMDiscoveryFilter Request Body

None

Specifies the hosted virtual machine discovery filter items in the machine group.

errorPolicy

String

Omit

Determines if the call will throw an error when encountering an invalid ID.

Throw: The entire request will be rejected.
Omit: The problem area will be omitted but the rest of the request will be completed.

VMDiscoveryFilter Request Body

Name	Required?	Type	Default Value	Description
adminCredentialId	No	Guid	None	The unique identifier of the credential associated with the admin credential.
inventoryPath	Yes	String	None	The virtual inventory path that describes the location. Example: /Server/vm/QA/vm-qa-w81x64-1
note	No	String	None	A user-specified note or description.
serverName	Yes	String	None	The name of the server or hypervisor.

Example with Sample Response

Create an empty machine group named "Sample Group"

POST Request

Copy

https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups

    {
        "name": "Sample Group",
        "description":"A sample group created using the REST API",
        "path": "TestPath",
        "credentialId": "684a5bb0-fabb-43f7-9bef-db02eb25a83b",
        "serverFilterTypes": "All"
    }

Sample Response

Copy

{
    "creator": "DOMAIN\\joe.coder",
    "credentialId": "684a5bb0-fabb-43f7-9bef-db02eb25a83b",
    "description": "A sample group created using the REST API",
    "id": 7,
    "isBuiltIn": false,
    "isReadOnly": false,
    "links": {
        "self": {
            "href": "https://device-name.example.com:3121/st/console/api/v1.0/machinegroups/7"
        },
        "discoveryfilters": {
            "href": "https://device-name.example.com:3121/st/console/api/v1.0/machinegroups/7/discoveryfilters"
        },
        "virtualmachinediscoveryfilters": {
            "href": "https://device-name.example.com:3121/st/console/api/v1.0/machinegroups/7/virtualmachinediscoveryfilters"
        },
        "usedby": {
            "href": "https://device-name.example.com:3121/st/console/api/v1.0/machinegroups/7/usedby"
        }
    },
    "name": "Sample Group",
    "path": "TestPath",
    "serverFilterTypes": "All",
    "virtualMachineDiscoveryFilters": []
}

Other Request Examples

Delete several items from the machine group with ID 8

DELETE Request

Copy

https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/8/discoveryFilters

    {
        "Ids": [9, 10, 11],
        "ErrorPolicy": "Omit"
    }

Create a machine group containing one machine and associated credentials

POST Request

Copy

https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups

{
    "name": "Example Machine Group",
    "credentialId": "01234567-89AB-CDEF-0123-456789ABCDEF",
    "description":"A machine group example",
    "path":"Path1",
    "discoveryFilters":[ {
        "adminCredentialId": "98765432-10AB-CDEF-0123-456789ABCDEF",
        "category": "MachineName",
        "name": "W2K12R2.dev.domainname.com",
        "isExcluded": "False"
    }]
}

Add a machine, an IP address, an IP range, an OU, a domain, a nested group and a virtual server to an existing machine group

POST Request

Copy

https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/38/discoveryfilters

{
    "errorPolicy": "Throw",
    "discoveryFilters":[{
        "category": "MachineName",
        "name": "TestMachine3"
    },
    {
        "category": "IPAddress",
        "name": "192.168.1.1"
    },
    {
        "category": "IPRange",
        "name": "10.114.250.1-10.114.250.255"
    },
    {
        "category": "OrganizationalUnit",
        "name": "OU=OU Sample,DC=ab1,DC=testlab,DC=example,DC=com"
    },
    {
        "category": "Domain",
        "name": "example.com"
    },
    {
        "category": "NestedGroup",
        "name": "SampleGroup
    },
    {
        "category": "VirtualServerWildcard",
        "name": "servername.example.com"
    }
    ]
}

Add a hosted virtual machine to the machine group with ID 38

In this example, the server must have been previously added to the virtual inventory.

POST Request

Copy

https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/38/virtualmachinediscoveryfilters

{
    "virtualMachineDiscoveryFilters": [
    {
        "serverName": "vserver.example.com",
        "AdminCredentialId": "fffbe3f5-42e1-40a7-b3d4-6d2dd9bcb1fd",
        "inventoryPath": "/GRYFFINDOR/vm/TEST/VMH-QA-W81X64-2",
        "note": "Hosted VM: Windows 81 64-bit"
    }
    ]
}

Rename an existing machine group

PUT Request

Copy

https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/4

{
    "name": "NewName"
}

Modify an IP range that is defined in an existing machine group

PUT Request

Copy

https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/4/discoveryFilters/30

{
    "category": "IPRange",
    "name": "192.168.1.1-192.168.1.40"
}

Modify a hosted VM that is defined in an existing machine group

PUT Request

Copy

https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/38/virtualmachinediscoveryfilters/12

{
    "serverName": "vCenter.example.com",
    "inventoryPath": "/server/vm/w81x64",
    "adminCredential": "a3224455-d49e-4666-af29-3aebc58a365a"
}

PowerShell Example

This example shows how to create a credential and then a machine group that contains some initial discovery filter items. It then adds a virtual server and a nested group. Finally, it updates the group credential and the discovery filter credential.

Copy

    $credBody = @{ name = [GUID]::NewGuid(); userName = "administrator"; password = @{ clearText = "ExamplePW123" }} | ConvertTo-Json -depth 10
    $securityControlsCred = Invoke-RestMethod -UseDefaultCredentials -Method Post -Body $credBody "https://jdoe-z789:3121/st/console/api/v1.0/credentials" -ContentType "application/json"
    
# create machine group

    $mgBody = @{ Name = [Guid]::NewGuid()
        DiscoveryFIlters =
        @(
            @{ category = "MachineName"; name = "test-w10x64-1" }
            @{ category = "IPAddress"; name = "10.114.250.98" }
            @{ category = "IPRange"; name = "10.114.250.1-10.114.250.255" }
            @{ category = "OrganizationalUnit"; name = "OU=OU JohnD,DC=test3,DC=testlab,DC=example,DC=com"; containerCredentialId = $securityControlsCred.id }
            @{ category = "Domain"; name = "example.com"; containerCredentialId = $securityControlsCred.id }
            @{ category = "MachineFile"; name = "c:\machines.txt" }
        )
        VirtualMachineDiscoveryFilters =
        @(
            @{ ServerName = "gryffindor.example.com"; inventoryPath = "/ourvms/test/TEST-W81X64-1" },
            @{ ServerName = "gryffindor.example.com"; inventoryPath = "/ourvms/test/TEST-W2K12X64-1" }
        )
        } | ConvertTo-Json -depth 10
    $mg = Invoke-RestMethod -UseDefaultCredentials -Method Post -Body $mgBody "https://jdoe-z789:3121/st/console/api/v1.0/machineGroups" -ContentType "application/json"
    
# add virtual server wildcard discovery filter - The server must have already been added to the virtual inventory, containerCredentialId does not need to be specified because it is retrieved from the virtual inventory.

    $dfBody = @{ discoveryFilters = @(@{ category = "VirtualServerWildcard"; name = "gryffindor.example.com" })} | ConvertTo-Json -Depth 10
    Invoke-RestMethod -UseDefaultCredentials -Method Post -Body $dfBody $mg.links.discoveryfilters.href -ContentType "application/json"
    
# add 'My Machine' as a nested group discovery filter

    $group = Invoke-RestMethod -UseDefaultCredentials -Method Get "https://jdoe-z789:3121/st/console/api/v1.0/machineGroups?Name=My%20Machine" -ContentType "application/json"
    $dfBody = @{ discoveryFilters = @(@{ category = "NestedGroup"; name = $group.value[0].name; nestedGroupId = $group.value[0].id })} | ConvertTo-Json -Depth 10
    Invoke-RestMethod -UseDefaultCredentials -Method Post -Body $dfBody $mg.links.discoveryfilters.href -ContentType "application/json"
    
# Update the machine group credential

    $mg | Add-Member -MemberType NoteProperty -Name "CredentialId" -Value $securityControlsCred.Id
    Invoke-RestMethod -UseDefaultCredentials -Method Put -Body ($mg | ConvertTo-Json -depth 10) $mg.links.self.href -ContentType "application/json"
    
# Update the first discovery filters credential

    $filters = Invoke-RestMethod -UseDefaultCredentials $mg.links.discoveryfilters.href
    Invoke-RestMethod -UseDefaultCredentials -Method Put ($filters.value[0].links.self.href + "/credentials?adminCredentialId=" + $securityControlsCred.id)

Output Models

MachineGroup

Name	Type	Description
connectionMethod	Enum	Specifies the method used to connect to the machine.
creator	String	The name of the user who created the machine group. Example: MyDomain\\John.Doe
credentialId	Guid	The unique identifier of the credential associated with the machine group.
description	String	Provides a description of the machine group.
discoveryFilters	DiscoveryFilters[]	Specifies the machines and containers in the machine group.
id	Integer	The unique identifier of the machine group.
isBuiltIn	Boolean	Specifies if the machine group is a built-in (predefined) group such as My Machine or My Domain.
isReadOnly	Boolean	Specifies if the machine group is editable. All user-defined machine groups are editable, as well as the My Test Machines group.
links	Links	Shows the related URLs for each machine group, the discoveryfilters, the virtualmachinediscoveryfilters and the usedby list.
name	String	The unique, user-defined name of the machine group.
path	String	The path that describes the location of the machine group within the My Machine Groups list in the navigation pane. Example: Lab\Servers
serverFilterTypes	ServerFilterTypes[]	The server filter types that will be included when scanning a machine group.
virtualMachineDiscoveryFilters	VirtualMachineDiscoveryFilter[]	Specifies the hosted virtual machines in the machine group.

Discovery Filters

Name	Type	Description
adminCredentialID	Guid	The ID of the associated administrative credential ID (if any).
category	DiscoveryFilterType	The type of filter or machine group item.
containerCredentialId	Guid	The ID of the associated browse or container credential ID (if any).
id	Integer	The unique identifier of the item.
includeChildOU	Boolean	Include child OUs.
isExcluded	Boolean	Is the item included or excluded during the operation?
links	Links	Shows the related URL for the discovery filter.
name	String	The filter or endpoint name.
nestedGroupId	Integer	The nested group ID.
note	String	A user-specified note or description.

DiscoveryFilterType

An enumerated type that defines what category an item belongs to. These values will be explicitly defined with specific number values because they map to integer type information contained in the database and in previous versions of the product.

Name	Description
machineName	Represents that a discovery filter was added as a machine name.
domain	Represents that a discovery filter was added as a domain.
ipAddress	Represents that a discovery filter was added as a single IP address.
ipRange	Represents that a discovery filter was added as a range of IP addresses.
machineFile	Represents that a discovery filter was added from a list of machine names.
domainFile	Represents that a discovery filter was added from a list of domains.
ipRangeFile	Represents that a discovery filter was added from a list of IP ranges.
ipAddressFile	Represents that a discovery filter was added as a list of IP addresses.
organizationalUnit	Represents that a discovery filter was added as an organizational unit. When searching via OU, the OU name should be properly escaped for any LDAP special characters.
nestedGroup	Represents that a discovery filter was added as a nested group.
virtualServerWildcard	Represents that a discovery filter was added as a virtual server wildcard.
The items that follow apply only to virtualMachineDiscoveryFilters.
virtualServerCenterHostedOfflineSystem	Represents that a virtual machine discovery filter was added as a hosted VM.
offlineDirectory or offlineImage	Represents an offline VM that resides on a workstation. The item was added to the machine group using the product user interface (adding workstation VMs via the REST API is currently not supported).

ServerFilterTypes

Name	Description
workstation	Specifies the workstation's operating system.
server	Specifies the server's operating system.
sqlServer	Specifies if a machine is running SQL Server.
domainController	Specifies if a machine is a domain controller.
printServer	Specifies if a machine is a print server.
iisServer	Specifies if a machine is an IIS server.

UsedBy

Name	Type	Description
name	String	The name of the item using the machine group.
usageType	Enum	The type of component using the machine group.

VirtualMachineDiscoveryFilter

Name	Type	Description
adminCredentialID	Guid	The ID of the associated administrative credential ID (if any).
category	DiscoveryFilterType	The type of filter or machine group item.
id	Int32	The unique identifier of the item.
inventoryPath	String	The inventory path returned from a hypervisor or vCenter. Shows the images that are contained on the hypervisor or vCenter.
links	Links	Shows the related URL for the discovery filter.
note	String	A user-specified note or description.
serverName	String	The server (vCenter) name.

VirtualImage

Name	Type	Description
hostName	String	The host name.
id	Int32	The unique identifier of the item
inventoryPath	String	The inventory path.
ipAddress	IDAddress	The IP address.
lastKnownPowerState	VirtualMachineState	The last known power state.
links	Links	The links associated with the image
name	String	The name of the item.
runningStatus	ToolsRuningStatus	The VMware tools running status.
versionStatus	ToolsVersionStatus	The VMware tools version status

Machine Groups

Base URL

Supported Requests

Input Models

Example with Sample Response

Create an empty machine group named "Sample Group"

POST Request

Sample Response

Other Request Examples

DELETE Request

DELETE Request

GET Request

GET Request

GET Request

GET Request

GET Request

GET Request

POST Request

POST Request

POST Request

PUT Request

PUT Request

PUT Request

PUT Request

PUT Request

PUT Request

Output Models